
/*
 * Copyright 2002-2019 the original author or authors.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */
/*
 *版权所有2002-2019原作者。
 *
 *根据Apache许可证2.0版（“许可证”）获得许可；
 *除非符合许可证，否则不得使用此文件。
 *您可以在以下地址获取许可证副本：
 *
 *      https://www.apache.org/licenses/LICENSE-2.0
 *
 *除非适用法律要求或书面同意，软件
 *根据许可证分发的内容是按“原样”分发的，
 *无任何明示或暗示的保证或条件。
 *有关管理权限和
 *许可证下的限制。
 */

package org.springframework.beans.factory.annotation;

import java.lang.annotation.Documented;
import java.lang.annotation.ElementType;
import java.lang.annotation.Retention;
import java.lang.annotation.RetentionPolicy;
import java.lang.annotation.Target;

/**
 * Marks a constructor, field, setter method, or config method as to be autowired by
 * Spring's dependency injection facilities. This is an alternative to the JSR-330
 * {@link jakarta.inject.Inject} annotation, adding required-vs-optional semantics.
 *
 * <h3>Autowired Constructors</h3>
 * <p>Only one constructor of any given bean class may declare this annotation with the
 * {@link #required} attribute set to {@code true}, indicating <i>the</i> constructor
 * to autowire when used as a Spring bean. Furthermore, if the {@code required}
 * attribute is set to {@code true}, only a single constructor may be annotated
 * with {@code @Autowired}. If multiple <i>non-required</i> constructors declare the
 * annotation, they will be considered as candidates for autowiring. The constructor
 * with the greatest number of dependencies that can be satisfied by matching beans
 * in the Spring container will be chosen. If none of the candidates can be satisfied,
 * then a primary/default constructor (if present) will be used. Similarly, if a
 * class declares multiple constructors but none of them is annotated with
 * {@code @Autowired}, then a primary/default constructor (if present) will be used.
 * If a class only declares a single constructor to begin with, it will always be used,
 * even if not annotated. An annotated constructor does not have to be public.
 *
 * <h3>Autowired Fields</h3>
 * <p>Fields are injected right after construction of a bean, before any config methods
 * are invoked. Such a config field does not have to be public.
 *
 * <h3>Autowired Methods</h3>
 * <p>Config methods may have an arbitrary name and any number of arguments; each of
 * those arguments will be autowired with a matching bean in the Spring container.
 * Bean property setter methods are effectively just a special case of such a general
 * config method. Such config methods do not have to be public.
 *
 * <h3>Autowired Parameters</h3>
 * <p>Although {@code @Autowired} can technically be declared on individual method
 * or constructor parameters since Spring Framework 5.0, most parts of the
 * framework ignore such declarations. The only part of the core Spring Framework
 * that actively supports autowired parameters is the JUnit Jupiter support in
 * the {@code spring-test} module (see the
 * <a href="https://docs.spring.io/spring/docs/current/spring-framework-reference/testing.html#testcontext-junit-jupiter-di">TestContext framework</a>
 * reference documentation for details).
 *
 * <h3>Multiple Arguments and 'required' Semantics</h3>
 * <p>In the case of a multi-arg constructor or method, the {@link #required} attribute
 * is applicable to all arguments. Individual parameters may be declared as Java-8 style
 * {@link java.util.Optional} or, as of Spring Framework 5.0, also as {@code @Nullable}
 * or a not-null parameter type in Kotlin, overriding the base 'required' semantics.
 *
 * <h3>Autowiring Arrays, Collections, and Maps</h3>
 * <p>In case of an array, {@link java.util.Collection}, or {@link java.util.Map}
 * dependency type, the container autowires all beans matching the declared value
 * type. For such purposes, the map keys must be declared as type {@code String}
 * which will be resolved to the corresponding bean names. Such a container-provided
 * collection will be ordered, taking into account
 * {@link org.springframework.core.Ordered Ordered} and
 * {@link org.springframework.core.annotation.Order @Order} values of the target
 * components, otherwise following their registration order in the container.
 * Alternatively, a single matching target bean may also be a generally typed
 * {@code Collection} or {@code Map} itself, getting injected as such.
 *
 * <h3>Not supported in {@code BeanPostProcessor} or {@code BeanFactoryPostProcessor}</h3>
 * <p>Note that actual injection is performed through a
 * {@link org.springframework.beans.factory.config.BeanPostProcessor
 * BeanPostProcessor} which in turn means that you <em>cannot</em>
 * use {@code @Autowired} to inject references into
 * {@link org.springframework.beans.factory.config.BeanPostProcessor
 * BeanPostProcessor} or
 * {@link org.springframework.beans.factory.config.BeanFactoryPostProcessor BeanFactoryPostProcessor}
 * types. Please consult the javadoc for the {@link AutowiredAnnotationBeanPostProcessor}
 * class (which, by default, checks for the presence of this annotation).
 *
 * @author Juergen Hoeller
 * @author Mark Fisher
 * @author Sam Brannen
 * @since 2.5
 * @see AutowiredAnnotationBeanPostProcessor
 * @see Qualifier
 * @see Value
 */
/**
 *将构造函数、字段、setter方法或config方法标记为由
 *Spring的依赖注入设施。这是JSR-330的替代方案
 *｛@linkjakarta.inject.inject｝注释，添加了必需的和可选的语义。
 *
 *<h3>自动连线构造器</h3>
 *＜p＞任何给定bean类的只有一个构造函数可以使用
 *｛@link#required｝属性设置为｛@code true｝，表示＜i＞＜/i＞构造函数
 *当用作Spring bean时自动连线。此外，如果需要｛@code｝
 *属性设置为｛@code true｝，只能注释一个构造函数
 *使用｛@code@Autowired｝。如果多个＜i＞非必需的＜/i＞构造函数声明
 *注释，它们将被视为自动布线的候选对象。构造函数
 *匹配bean可以满足最大数量的依赖关系
 *将选择Spring容器中的。如果没有一个候选能够被满足，
 *则将使用主/默认构造函数（如果存在）。类似地，如果
 *类声明了多个构造函数，但没有一个用
 *｛@code@Autowired｝，则将使用主/默认构造函数（如果存在）。
 *如果一个类只声明一个构造函数开始，
 *即使没有注释。带注释的构造函数不必是公共的。
 *
 *<h3>自动连线字段</h3>
 *＜p＞在构建bean之后，在任何配置方法之前，立即注入字段
 *被调用。这样的配置字段不必是公共的。
 *
 *<h3>自动连线方法</h3>
 *＜p＞配置方法可以具有任意名称和任意数量的参数；每个
 *这些参数将与Spring容器中的匹配bean自动关联。
 *Bean属性设置器方法实际上只是这样一种通用方法的特例
 *config方法。这样的配置方法不必是公共的。
 *
 *<h3>自动连线参数</h3>
 *＜p＞虽然｛@code@Autowired｝在技术上可以在单个方法上声明
 *或自Spring Framework 5.0以来的构造函数参数
 *框架忽略此类声明。核心Spring框架的唯一部分
 *主动支持自动连线参数的是JUnit Jupiter在
 *｛@code spring test｝模块（请参见
 *<a href=“https://docs.spring.io/spring/docs/current/spring-framework-reference/testing.html#testcontext-junit jupiter di“>TestContext框架</a>
 *有关详细信息，请参阅文档）。
 *
 *<h3>多个参数和“必需”语义</h3>
 *＜p＞对于多参数构造函数或方法，｛@link#required｝属性
 *适用于所有参数。单个参数可以声明为Java-8样式
 *｛@linkjava.util.Optional｝或者，从Spring Framework 5.0起，也可以称为｛@code@Nullable｝
 *或Kotlin中的非空参数类型，覆盖基本“必需”语义。
 *
 *<h3>自动布线阵列、集合和映射</h3>
 *＜p＞对于数组，｛@link java.util.Collection｝或｛@linkjava.util.Map｝
 *依赖类型，容器自动连接所有与声明值匹配的bean
 *类型。为此，映射键必须声明为类型｛@code String｝
 *它将被解析为相应的bean名称。提供这样的容器
 *考虑到
 *｛@link org.springframework.core.Ordered Ordered｝和
 *｛@link org.springframework.core.annotation.Order@Order｝目标的值
 *组件，否则遵循容器中的注册顺序。
 *或者，单个匹配的目标bean也可以是一般类型的
 *｛@code Collection｝或｛@codeMap｝本身，因此被注入。
 *
 *<h3>｛@code BeanPostProcessor｝或｛@codeBeanFactoryPostProcessor｝</h3>
 *＜p＞注意，实际注射是通过
 *｛@link org.springframework.beans.factory.config.BeanPostProcessor｝
 *BeanPostProcessor｝，这反过来意味着您不能</em>
 *使用｛@code@Autowired｝将引用注入
 *｛@link org.springframework.beans.factory.config.BeanPostProcessor｝
 *BeanPostProcessor｝或
 *｛@link org.springframework.beans.factory.config.BeanFactoryPostProcessorBeanFactoryPostProcesser｝
 *类型。请查阅javadoc获取｛@link AutowiredAnnotationBeanPostProcessor｝
 *类（默认情况下，该类检查该注释的存在）。
 *
 *@作者Juergen Hoeller
 *@作者Mark Fisher
 *@作者Sam Brannen
 *@自2.5
 *@参见AutowiredAnnotationBeanPostProcessor
 *@参见限定符
 *@参见值
 */
@Target({ElementType.CONSTRUCTOR, ElementType.METHOD, ElementType.PARAMETER, ElementType.FIELD, ElementType.ANNOTATION_TYPE})
@Retention(RetentionPolicy.RUNTIME)
@Documented
public @interface Autowired {

	/**
	 * Declares whether the annotated dependency is required.
	 * <p>Defaults to {@code true}.
	 */
	/**
	 *声明是否需要带注释的依赖项。
	 *＜p＞默认为｛@code true｝。
	 */
	boolean required() default true;

}
